home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / progem.arc / gem3.asc < prev    next >
Text File  |  1987-10-10  |  16KB  |  354 lines
  1.                        **Professional GEM**
  2.                            by Tim Oren
  3.  
  4.                         THE DIALOG HANDLER
  5.                              11/7/85
  6.  
  7.  
  8.                        A MEANINGFUL DIALOG
  9.  
  10.    This issue of ST PRO GEM begins an exploration of ST GEM's dialog
  11. handler.  I will discuss basic system calls for presenting the
  12. dialog, and then continue with techniques for initializing and
  13. reading on/off button and "radio" button objects.  We  will also take
  14. some short side-trips into the operation of the GEM Resource
  15. Construction Set to assist you in building these dialogs.
  16.  
  17.    There are a number of short C routines which accompany this column.
  18. These are stored as file GEMCL3.XMO in DL 5 on SIG*ATARI. Before
  19. reading this column, you should visit SIG*ATARI (go pcs-132) and
  20. download this file.
  21.  
  22.                           DEFINING TERMS
  23.  
  24.    A dialog box is an "interactive form" in which the user may enter
  25. text and indicate selections by pointing with the mouse. Dialogs in
  26. GEM are "modal", that is, when a dialog is activated other screen
  27. functions such as menus and  window controls are suspended until the
  28. dialog is completed.
  29.  
  30.    In most cases, the visual structure of a GEM dialog is specified
  31. within your application's resource file.  The GEM Resource
  32. Construction Set (RCS) is used to build a picture of the dialog.
  33.  
  34.    When the RCS writes out a resource, it converts that picture into a
  35. tree of GEM drawing objects and stores this data structure within the
  36. resource.  Before your application can  display the dialog, it must
  37. load this resource file and find the  address of the tree which
  38. defines the dialog.
  39.  
  40.    To load a resource, the AES checks its size and allocates memory for
  41. the load.  It then reads in the resource, adjusting internal pointers
  42. to reflect the load address.  Finally, the object sizes stored in the
  43. resource are converted from characters to pixels using the system
  44. font size.
  45.  
  46.    (A note for those with Macintosh experience:  Although Mac and GEM
  47. resources share a name, there are fundamental differences which can
  48. be misleading.  A Mac resource is a fork within a file; a GEM
  49. resource is a TOS file by itself.  Mac resources may be paged in and
  50. out of memory; GEM resources are monolithic.  GEM resources are
  51. internally tree structured; Mac resources are not.  Finally, Mac
  52. resources include font information, while ST GEM does this with font
  53. loading at the VDI level.)
  54.  
  55.    The resource load is done with the GEM AES call:
  56.  
  57.    ok = rsrc_load(ADDR("MYAPP.RSC"));
  58.  
  59.    "MYAPP" should be replaced with the name of your program. Resources
  60. conventionally have the same primary name as their application, with
  61. the RSC extent name instead of PRG.  The ok flag returned by
  62. rsrc_load will be FALSE is anything went wrong during the load.
  63.  
  64.    The most common causes of failure are the resource not being in the
  65. application's subdirectory, or lack of sufficient memory for GEM to
  66. allocate space for the resource.  If this happens, you must terminate
  67. the program immediately.
  68.  
  69.    Once you have loaded the resource, you find the address of a dialog's
  70. object tree with:
  71.  
  72.    rsrc_gaddr(R_TREE, MYDIALOG, &tree);
  73.  
  74. Tree is a 32-bit variable which will receive the address of the root
  75. node of the tree.
  76.  
  77.    The mnemonic MYDIALOG should be replaced with the name you gave your
  78. dialog when defining it in the RCS.  At the same time that it writes
  79. the resource, RCS generates a corresponding .H file containing tree
  80. and object names.  In order to use these mnemonics within your
  81. program, you must include the name file in your compile:  #include
  82. "MYAPP.H"
  83.  
  84.                             BUG ALERT!
  85.  
  86.    When using the DRI/Alcyon C compiler, .H files must be in the
  87. compiler's home directory or they will not be found.  This is
  88. especially annoying using a two floppy drive ST development system.
  89. The only way around this is to explicitly  reference an alternate
  90. disk in the #include, for instance:  "B:MYAPP.H"
  91.  
  92.    Now that the address of the dialog tree has been found, you are ready
  93. to display it.  The standard (and minimal) sequence for doing so is
  94. given in routine hndl_dial() in the download.  We will now walk
  95. through each step in this procedure.
  96.  
  97.    The form_center call establishes the location of the dialog on the
  98. screen.  Dialog trees generated by the RCS have an undefined origin
  99. (upper-left corner).
  100.  
  101.    Form_center computes the upper-left location necessary to center the
  102. dialog on the screen, and inserts it into the OB_X and OB_Y fields of
  103. the ROOT object of the tree.  It also computes the screen rectangle
  104. which the dialog will occupy on screen and writes its pixel
  105. coordinates into variables xdial, ydial, wdial, and hdial.
  106.  
  107.    There is one peculiarity of form_center which occasionally causes
  108. trouble.  Normally the rectangle returned in xdial, etc., is exactly
  109. the same size as the basic dialog box.
  110.  
  111.    However, when the OUTLINED enhancement has been specified for the
  112. box, form_center adds a three pixel margin to the rectangle returned.
  113. This causes the screen area under the outline to be correctly redrawn
  114. later (see below).  Note that OUTLINED is part of the standard dialog
  115. box in the RCS.  Other enhancements, such as SHADOWED or "outside"
  116. borders are NOT handled in this fashion, and you must compensate  for
  117. them in your code.
  118.  
  119.    The next part of the sequence is a form_dial call with a zero
  120. parameter.  This reserves the screen for the dialog action about to
  121. occur. Note that the C binding given for form_dial in the DRI
  122. documents is in error: there are nine parameters, not five.  The
  123. first set of xywh arguments is actually used with form_dial calls 1
  124. and 2 only, but place holders must be supplied in all cases.
  125.  
  126.    The succeeding form_dial call (parameter one) animates a "zoom box"
  127. on the screen which moves and grows from the first screen rectangle
  128. given to the second rectangle, where the dialog will be displayed.
  129.  
  130.    The use of this call is entirely optional.  In choosing whether to
  131. use it or not, you should consider whether the origin of the "zoom"
  132. is relevant to the  operation.  For instance, a zoom from the menu
  133. bar is relatively meaningless, while a zoom from an object about to
  134. be edited in the dialog provides visual feedback to the user, showing
  135. whether the correct object was chosen.
  136.  
  137.    If the origin is not relevant, then the zoom is just a time-waster.
  138. If  you decide to include these effects, consider a "preferences"
  139. option in  your app which will allow the experienced and jaded user
  140. to turn them off in the interests of speed.
  141.  
  142.    The objc_draw call actually displays the dialog on the screen. Note
  143. that the address of the tree, the beginning drawing object, and the
  144. drawing depth are passed as arguments, as well as the rectangle
  145. allotted for the dialog.
  146.  
  147.    In general, dialogs (and parts of dialogs) are  ALWAYS drawn
  148. beginning at the ROOT (object zero).  When you want to draw  only a
  149. portion of the dialog, adjust the clipping rectangle, but not the
  150. object number.  This ensures that the background of the dialog is
  151. always  drawn correctly.
  152.  
  153.    The objc_xywh() utility in the download can be used to find the
  154. clipping rectangle for any object within a dialog, though you may
  155. have to allow an extra margin is you have used shadows, outlines, or
  156. outside borders with the object.
  157.  
  158.    Calling form_do transfers control to the AES, which animates the
  159. dialog for user interaction.  The address of the dialog tree is
  160. passed as a parameter.  The second paramter is the number of the
  161. editable object at which the text cursor will first be positioned.
  162. If you have no text fields, pass a zero.  Note that again the DRI
  163. documents are in error: passing a -1 default may crash the system.
  164. Also be careful that the default which you specify is actually a text
  165. field; no error checking is performed.
  166.  
  167.    The form_do call returns the number of the object on which the
  168. clicked to terminate the dialog.  Usually this is a button type
  169. object with the EXIT and SELECTABLE attributes set.  Setting the
  170. DEFAULT attribute as well will cause an exit on that object is a
  171. carriage return is struck while in the dialog.
  172.  
  173.    If the top bit of the return is set, it indicates that  the exit
  174. object had the TOUCHEXIT attribute an